Autogenerated HTML docs for v1.5.6.4-433-g09651
diff --git a/RelNotes-1.5.6.4.txt b/RelNotes-1.5.6.4.txt index 1304188..d8968f1 100644 --- a/RelNotes-1.5.6.4.txt +++ b/RelNotes-1.5.6.4.txt
@@ -28,16 +28,20 @@ be huge by saying "no common commits", but this was an unnecessary noise; it is already known by the user anyway. +* "git-http-fetch" would have segfaulted when pack idx file retrieved + from the other side was corrupt. + +* "git-index-pack" used too much memory when dealing with a deep delta chain. + * "git-mailinfo" (hence "git-am") did not correctly handle in-body [PATCH] line to override the commit title taken from the mail Subject header. * "git-rebase -i -p" lost parents that are not involved in the history being rewritten. -Contains other various documentation fixes. +* "git-rm" lost track of where the index file was when GIT_DIR was + specified as a relative path. --- -exec >/var/tmp/1 -echo O=$(git describe maint) -O=v1.5.6.3-21-gebcce31 -git shortlog --no-merges $O..maint +* "git-rev-list --quiet" was not quiet as advertised. + +Contains other various documentation fixes.
diff --git a/RelNotes-1.6.0.txt b/RelNotes-1.6.0.txt index b29ba25..7da62d0 100644 --- a/RelNotes-1.6.0.txt +++ b/RelNotes-1.6.0.txt
@@ -21,7 +21,9 @@ By default, packfiles created with this version uses delta-base-offset encoding introduced in v1.4.4. Pack idx files are using version 2 that allows larger packs and added robustness thanks to its CRC checking, -introduced in v1.5.2. +introduced in v1.5.2 and v1.4.4.5. If you want to keep your repositories +backwards compatible past these versions, set repack.useDeltaBaseOffset +to false or pack.indexVersion to 1, respectively. GIT_CONFIG, which was only documented as affecting "git config", but actually affected all git commands, now only affects "git config". @@ -134,6 +136,9 @@ * git-archive can be told to omit certain paths from its output using export-ignore attributes. +* git-archive uses the zlib default compression level when creating + zip archive. + * With -v option, git-branch describes the remote tracking statistics similar to the way git-checkout reports by how many commits your branch is ahead/behind. @@ -153,6 +158,8 @@ * git-clone can clone from a remote whose URL would be rewritten by configuration stored in $HOME/.gitconfig now. +* git-cvsserver learned to respond to "cvs co -c". + * git-diff --check now checks leftover merge conflict markers. * When remote side used to have branch 'foo' and git-fetch finds that now @@ -164,6 +171,8 @@ * fast-export learned to export and import marks file; this can be used to interface with fast-import incrementally. +* fast-import and fast-export learned to export and import gitlinks. + * git-rebase records the original tip of branch in ORIG_HEAD before it is rewound. @@ -208,6 +217,6 @@ --- exec >/var/tmp/1 -O=v1.5.6.3-436-g1f8dc67 +O=v1.5.6.4-432-g6796399 echo O=$(git describe refs/heads/master) git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
diff --git a/git-fast-import.html b/git-fast-import.html index 5b0932d..e9066a5 100644 --- a/git-fast-import.html +++ b/git-fast-import.html
@@ -875,6 +875,13 @@ <tt>120000</tt>: A symlink, the content of the file will be the link target. </p> </li> +<li> +<p> +<tt>160000</tt>: A gitlink, SHA-1 of the object refers to a commit in + another repository. Git links can only be specified by SHA or through + a commit mark. They are used to implement submodules. +</p> +</li> </ul></div> <div class="para"><p>In both formats <tt><path></tt> is the complete path of the file to be added (if not already existing) or modified (if already existing).</p></div> @@ -1464,7 +1471,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-06 05:16:45 UTC +Last updated 2008-07-20 01:23:33 UTC </div> </div> </body>
diff --git a/git-fast-import.txt b/git-fast-import.txt index 2d01d0d..c2f483a 100644 --- a/git-fast-import.txt +++ b/git-fast-import.txt
@@ -481,6 +481,9 @@ what you want. * `100755` or `755`: A normal, but executable, file. * `120000`: A symlink, the content of the file will be the link target. +* `160000`: A gitlink, SHA-1 of the object refers to a commit in + another repository. Git links can only be specified by SHA or through + a commit mark. They are used to implement submodules. In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing).
diff --git a/git-merge.html b/git-merge.html index 4616616..1e0bf58 100644 --- a/git-merge.html +++ b/git-merge.html
@@ -657,52 +657,41 @@ <div class="sectionbody"> <div class="para"><p>A merge is always between the current <tt>HEAD</tt> and one or more commits (usually, branch head or tag), and the index file must -exactly match the -tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when -it happens. In other words, <tt>git diff --cached HEAD</tt> must -report no changes.</p></div> -<div class="admonitionblock"> -<table><tr> -<td class="icon"> -<div class="title">Note</div> -</td> -<td class="content">This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the <tt>HEAD</tt> commit. The most -notable case is when your <tt>HEAD</tt> commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your <tt>HEAD</tt> commit. Also, your index entries -may have differences from your <tt>HEAD</tt> commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail.</td> -</tr></table> -</div> -<div class="para"><p>Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with <tt>git pull remote rbranch:lbranch</tt>, but your working tree, -<tt>.git/HEAD</tt> pointer and index file are left intact). In addition, -merge always sets <tt>.git/ORIG_HEAD</tt> to the original state of HEAD so -a problematic merge can be removed by using <tt>git reset ORIG_HEAD</tt>.</p></div> -<div class="para"><p>You may have local modifications in the working tree files. In -other words, <em>git-diff</em> is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything.</p></div> -<div class="para"><p>So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready.</p></div> -<div class="para"><p>When things cleanly merge, these things happen:</p></div> +match the tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) +when it starts out. In other words, <tt>git diff --cached HEAD</tt> must +report no changes. (One exception is when the changed index +entries are already in the same state that would result from +the merge anyway.)</p></div> +<div class="para"><p>Three kinds of merge can happen:</p></div> +<div class="ilist"><ul> +<li> +<p> +The merged commit is already contained in <tt>HEAD</tt>. This is the + simplest case, called "Already up-to-date." +</p> +</li> +<li> +<p> +<tt>HEAD</tt> is already contained in the merged commit. This is the + most common case especially when involved through <em>git pull</em>: + you are tracking an upstream repository, committed no local + changes and now you want to update to a newer upstream revision. + Your <tt>HEAD</tt> (and the index) is updated to at point the merged + commit, without creating an extra merge commit. This is + called "Fast-forward". +</p> +</li> +<li> +<p> +Both the merged commit and <tt>HEAD</tt> are independent and must be + tied together by a merge commit that has them both as its parents. + The rest of this section describes this "True merge" case. +</p> +</li> +</ul></div> +<div class="para"><p>The chosen merge strategy merges the two commits into a single +new source tree. +When things cleanly merge, these things happen:</p></div> <div class="olist"><ol> <li> <p> @@ -773,15 +762,16 @@ <p> Decide not to merge. The only clean-up you need are to reset the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; <em>git-reset</em> can + up working tree changes made by 2. and 3.; <em>git-reset --hard</em> can be used for this. </p> </li> <li> <p> Resolve the conflicts. <tt>git diff</tt> would report only the - conflicting paths because of the above 2. and 3. Edit the - working tree files into a desirable shape, <em>git-add</em> or <em>git-rm</em> + conflicting paths because of the above 2. and 3. + Edit the working tree files into a desirable shape + (<em>git mergetool</em> can ease this task), <em>git-add</em> or <em>git-rm</em> them, to make the index file contain what the merge result should be, and run <em>git-commit</em> to commit the result. </p> @@ -811,7 +801,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-15 15:48:34 UTC +Last updated 2008-07-20 01:23:33 UTC </div> </div> </body>
diff --git a/git-merge.txt b/git-merge.txt index 019e4ca..a7487d3 100644 --- a/git-merge.txt +++ b/git-merge.txt
@@ -57,50 +57,31 @@ A merge is always between the current `HEAD` and one or more commits (usually, branch head or tag), and the index file must -exactly match the -tree of `HEAD` commit (i.e. the contents of the last commit) when -it happens. In other words, `git diff --cached HEAD` must -report no changes. +match the tree of `HEAD` commit (i.e. the contents of the last commit) +when it starts out. In other words, `git diff --cached HEAD` must +report no changes. (One exception is when the changed index +entries are already in the same state that would result from +the merge anyway.) -[NOTE] -This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the `HEAD` commit. The most -notable case is when your `HEAD` commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your `HEAD` commit. Also, your index entries -may have differences from your `HEAD` commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail. +Three kinds of merge can happen: -Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with `git pull remote rbranch:lbranch`, but your working tree, -`.git/HEAD` pointer and index file are left intact). In addition, -merge always sets `.git/ORIG_HEAD` to the original state of HEAD so -a problematic merge can be removed by using `git reset ORIG_HEAD`. +* The merged commit is already contained in `HEAD`. This is the + simplest case, called "Already up-to-date." -You may have local modifications in the working tree files. In -other words, 'git-diff' is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything. +* `HEAD` is already contained in the merged commit. This is the + most common case especially when involved through 'git pull': + you are tracking an upstream repository, committed no local + changes and now you want to update to a newer upstream revision. + Your `HEAD` (and the index) is updated to at point the merged + commit, without creating an extra merge commit. This is + called "Fast-forward". -So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready. +* Both the merged commit and `HEAD` are independent and must be + tied together by a merge commit that has them both as its parents. + The rest of this section describes this "True merge" case. +The chosen merge strategy merges the two commits into a single +new source tree. When things cleanly merge, these things happen: 1. The results are updated both in the index file and in your @@ -142,12 +123,13 @@ * Decide not to merge. The only clean-up you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; 'git-reset' can + up working tree changes made by 2. and 3.; 'git-reset --hard' can be used for this. * Resolve the conflicts. `git diff` would report only the - conflicting paths because of the above 2. and 3. Edit the - working tree files into a desirable shape, 'git-add' or 'git-rm' + conflicting paths because of the above 2. and 3. + Edit the working tree files into a desirable shape + ('git mergetool' can ease this task), 'git-add' or 'git-rm' them, to make the index file contain what the merge result should be, and run 'git-commit' to commit the result. diff --git a/git-submodule.html b/git-submodule.html index 1ecc633..0c1b2a5 100644 --- a/git-submodule.html +++ b/git-submodule.html
@@ -329,22 +329,41 @@ </div> <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> -<div class="para"><p>Submodules are a special kind of tree entries which refer to a particular tree -state in another repository. The tree entry describes -the existence of a submodule with the given name and the exact revision that -should be used, while an entry in <tt>.gitmodules</tt> file gives the location of -the repository.</p></div> -<div class="para"><p>When checked out, submodules will maintain their own independent repositories -within their directories; the only link between the submodule and the "parent -project" is the tree entry within the parent project mentioned above.</p></div> -<div class="para"><p>This command will manage the tree entries and contents of the gitmodules file -for you, as well as inspecting the status of your submodules and updating them. -When adding a new submodule to the tree, the <em>add</em> subcommand is to be used. -However, when pulling a tree containing submodules, these will not be checked -out by default; the <em>init</em> and <em>update</em> subcommands will maintain submodules -checked out and at appropriate revision in your working tree. You can inspect -the current status of your submodules using the <em>submodule</em> subcommand and get -an overview of changes <em>update</em> would perform using the <em>summary</em> subcommand.</p></div> +<div class="para"><p>Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit.</p></div> +<div class="para"><p>They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the <em>subtree</em> merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route.</p></div> +<div class="para"><p>Submodules are composed from a so-called <tt>gitlink</tt> tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the <tt>.gitmodules</tt> file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see <em>submodule init</em>).</p></div> +<div class="para"><p>This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the <em>add</em> subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the <em>init</em> and <em>update</em> subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the <em>status</em> subcommand and get a detailed overview of the +difference between the index and checkouts using the <em>summary</em> +subcommand.</p></div> </div> <h2 id="_commands">COMMANDS</h2> <div class="sectionbody"> @@ -397,10 +416,15 @@ </dt> <dd> <p> - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - <tt>submodule.$name.url</tt>. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is <tt>submodule.$name.url</tt>. + This command does not alter existing information in .git/config. + You can then customize the submodule clone URLs in .git/config + for your local setup and proceed to <em>git submodule update</em>; + you can also just use <em>git submodule update --init</em> without + the explicit <em>init</em> step if you do not intend to customize + any submodule locations. </p> </dd> <dt> @@ -509,7 +533,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-17 08:08:29 UTC +Last updated 2008-07-20 01:23:35 UTC </div> </div> </body>
diff --git a/git-submodule.txt b/git-submodule.txt index bb4e6fb..829b032 100644 --- a/git-submodule.txt +++ b/git-submodule.txt
@@ -18,24 +18,44 @@ DESCRIPTION ----------- -Submodules are a special kind of tree entries which refer to a particular tree -state in another repository. The tree entry describes -the existence of a submodule with the given name and the exact revision that -should be used, while an entry in `.gitmodules` file gives the location of -the repository. +Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit. -When checked out, submodules will maintain their own independent repositories -within their directories; the only link between the submodule and the "parent -project" is the tree entry within the parent project mentioned above. +They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. -This command will manage the tree entries and contents of the gitmodules file -for you, as well as inspecting the status of your submodules and updating them. -When adding a new submodule to the tree, the 'add' subcommand is to be used. -However, when pulling a tree containing submodules, these will not be checked -out by default; the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. You can inspect -the current status of your submodules using the 'submodule' subcommand and get -an overview of changes 'update' would perform using the 'summary' subcommand. +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the 'add' subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the 'status' subcommand and get a detailed overview of the +difference between the index and checkouts using the 'summary' +subcommand. COMMANDS @@ -78,10 +98,15 @@ repository. This command is the default command for 'git-submodule'. init:: - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - `submodule.$name.url`. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is `submodule.$name.url`. + This command does not alter existing information in .git/config. + You can then customize the submodule clone URLs in .git/config + for your local setup and proceed to 'git submodule update'; + you can also just use 'git submodule update --init' without + the explicit 'init' step if you do not intend to customize + any submodule locations. update:: Update the registered submodules, i.e. clone missing submodules and
diff --git a/git-update-index.html b/git-update-index.html index be82155..90099e2 100644 --- a/git-update-index.html +++ b/git-update-index.html
@@ -452,6 +452,15 @@ filesystem that has very slow lstat(2) system call (e.g. cifs). </p> +<div class="para"><p>This option can be also used as a coarse file-level mechanism +to ignore uncommitted changes in tracked files (akin to what +<tt>.gitignore</tt> does for untracked files). +You should remember that an explicit <em>git add</em> operation will +still cause the file to be refreshed from the working tree. +Git will fail (gracefully) in case it needs to modify this file +in the index e.g. when merging in a commit; +thus, in case the assumed-untracked file is changed upstream, +you will need to handle the situation manually.</p></div> </dd> <dt> -g @@ -781,7 +790,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-06 05:17:06 UTC +Last updated 2008-07-20 01:23:35 UTC </div> </div> </body>
diff --git a/git-update-index.txt b/git-update-index.txt index a91fd21..6b930bc 100644 --- a/git-update-index.txt +++ b/git-update-index.txt
@@ -88,6 +88,16 @@ sometimes helpful when working with a big project on a filesystem that has very slow lstat(2) system call (e.g. cifs). ++ +This option can be also used as a coarse file-level mechanism +to ignore uncommitted changes in tracked files (akin to what +`.gitignore` does for untracked files). +You should remember that an explicit 'git add' operation will +still cause the file to be refreshed from the working tree. +Git will fail (gracefully) in case it needs to modify this file +in the index e.g. when merging in a commit; +thus, in case the assumed-untracked file is changed upstream, +you will need to handle the situation manually. -g:: --again::
diff --git a/git.html b/git.html index 53a20c7..ad11a4e 100644 --- a/git.html +++ b/git.html
@@ -2024,7 +2024,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-14 03:12:31 UTC +Last updated 2008-07-20 01:23:36 UTC </div> </div> </body>
diff --git a/git.txt b/git.txt index 27b9d31..44ea35e 100644 --- a/git.txt +++ b/git.txt
@@ -43,12 +43,13 @@ branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.6.3/git.html[documentation for release 1.5.6.3] +* link:v1.5.6.4/git.html[documentation for release 1.5.6.4] * release notes for - link:RelNotes-1.5.6.3.txt[1.5.6.3]. - link:RelNotes-1.5.6.2.txt[1.5.6.2]. - link:RelNotes-1.5.6.1.txt[1.5.6.1]. + link:RelNotes-1.5.6.4.txt[1.5.6.4], + link:RelNotes-1.5.6.3.txt[1.5.6.3], + link:RelNotes-1.5.6.2.txt[1.5.6.2], + link:RelNotes-1.5.6.1.txt[1.5.6.1], link:RelNotes-1.5.6.txt[1.5.6]. * link:v1.5.5.4/git.html[documentation for release 1.5.5.4]
diff --git a/gitignore.html b/gitignore.html index 3c8799b..9f0bd93 100644 --- a/gitignore.html +++ b/gitignore.html
@@ -325,9 +325,14 @@ <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> <div class="para"><p>A <tt>gitignore</tt> file specifies intentionally untracked files that -git should ignore. Each line in a <tt>gitignore</tt> file specifies a -pattern.</p></div> -<div class="para"><p>When deciding whether to ignore a path, git normally checks +git should ignore. +Note that all the <tt>gitignore</tt> files really concern only files +that are not already tracked by git; +in order to ignore uncommitted changes in already tracked files, +please refer to the <em>git update-index --assume-unchanged</em> +documentation.</p></div> +<div class="para"><p>Each line in a <tt>gitignore</tt> file specifies a pattern. +When deciding whether to ignore a path, git normally checks <tt>gitignore</tt> patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of precedence, the last matching pattern decides the outcome):</p></div> @@ -481,7 +486,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2008-07-06 05:17:10 UTC +Last updated 2008-07-20 01:23:36 UTC </div> </div> </body>
diff --git a/gitignore.txt b/gitignore.txt index fc0efd8..59321a2 100644 --- a/gitignore.txt +++ b/gitignore.txt
@@ -13,9 +13,14 @@ ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. +git should ignore. +Note that all the `gitignore` files really concern only files +that are not already tracked by git; +in order to ignore uncommitted changes in already tracked files, +please refer to the 'git update-index --assume-unchanged' +documentation. +Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks `gitignore` patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of
diff --git a/technical/api-run-command.html b/technical/api-run-command.html index f4f5555..acbc323 100644 --- a/technical/api-run-command.html +++ b/technical/api-run-command.html
@@ -3,7 +3,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> -<meta name="generator" content="AsciiDoc 7.0.2" /> +<meta name="generator" content="AsciiDoc 8.2.5" /> <style type="text/css"> /* Debug borders */ p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { @@ -16,8 +16,13 @@ margin: 1em 5% 1em 5%; } -a { color: blue; } -a:visited { color: fuchsia; } +a { + color: blue; + text-decoration: underline; +} +a:visited { + color: fuchsia; +} em { font-style: italic; @@ -39,13 +44,18 @@ line-height: 1.3; } -h1 { +h1, h2, h3 { border-bottom: 2px solid silver; } h2 { - border-bottom: 2px solid silver; padding-top: 0.5em; } +h3 { + float: left; +} +h3 + * { + clear: left; +} div.sectionbody { font-family: serif; @@ -70,7 +80,7 @@ color: #527bbd; font-family: sans-serif; font-weight: bold; - font-size: 1.2em; + font-size: 1.1em; } span#email { } @@ -139,6 +149,9 @@ padding: 0.5em; } +div.listingblock { + margin-right: 0%; +} div.listingblock > div.content { border: 1px solid silver; background: #f4f4f4; @@ -148,9 +161,13 @@ div.quoteblock > div.content { padding-left: 2.0em; } -div.quoteblock .attribution { + +div.attribution { text-align: right; } +div.verseblock + div.attribution { + text-align: left; +} div.admonitionblock .icon { vertical-align: top; @@ -194,13 +211,12 @@ ul, ol { list-style-position: outside; } -ol.olist2 { +div.olist2 ol { list-style-type: lower-alpha; } div.tableblock > table { - border-color: #527bbd; - border-width: 3px; + border: 3px solid #527bbd; } thead { font-family: sans-serif; @@ -214,6 +230,9 @@ margin-top: 0.8em; margin-bottom: 0.8em; } +div.hlist td { + padding-bottom: 5px; +} td.hlist1 { vertical-align: top; font-style: italic; @@ -226,6 +245,32 @@ @media print { div#footer-badges { display: none; } } + +div#toctitle { + color: #527bbd; + font-family: sans-serif; + font-size: 1.1em; + font-weight: bold; + margin-top: 1.0em; + margin-bottom: 0.1em; +} + +div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { + margin-top: 0; + margin-bottom: 0; +} +div.toclevel2 { + margin-left: 2em; + font-size: 0.9em; +} +div.toclevel3 { + margin-left: 4em; + font-size: 0.9em; +} +div.toclevel4 { + margin-left: 6em; + font-size: 0.9em; +} /* Workarounds for IE6's broken and incomplete CSS2. */ div.sidebar-content { @@ -254,6 +299,9 @@ border-left: 2px solid silver; padding-left: 0.5em; } + +/* IE6 sets dynamically generated links as visited. */ +div#toc a:visited { color: blue; } </style> <title>run-command API</title> </head> @@ -263,17 +311,17 @@ </div> <div id="preamble"> <div class="sectionbody"> -<p>The run-command API offers a versatile tool to run sub-processes with +<div class="para"><p>The run-command API offers a versatile tool to run sub-processes with redirected input and output as well as with a modified environment -and an alternate current directory.</p> -<p>A similar API offers the capability to run a function asynchronously, +and an alternate current directory.</p></div> +<div class="para"><p>A similar API offers the capability to run a function asynchronously, which is primarily used to capture the output that the function -produces in the caller in order to process it.</p> +produces in the caller in order to process it.</p></div> </div> </div> -<h2>Functions</h2> +<h2 id="_functions">Functions</h2> <div class="sectionbody"> -<dl> +<div class="vlist"><dl> <dt> <tt>start_command</tt> </dt> @@ -304,7 +352,7 @@ </p> </dd> <dt> -<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_dir</tt>, <tt>run_command_v_opt_cd_env</tt> +<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_cd</tt>, <tt>run_command_v_opt_cd_env</tt> </dt> <dd> <p> @@ -337,21 +385,21 @@ started with start_async(). </p> </dd> -</dl> +</dl></div> </div> -<h2>Data structures</h2> +<h2 id="_data_structures">Data structures</h2> <div class="sectionbody"> -<ul> +<div class="ilist"><ul> <li> <p> <tt>struct child_process</tt> </p> </li> -</ul> -<p>This describes the arguments, redirections, and environment of a -command to run in a sub-process.</p> -<p>The caller:</p> -<ol> +</ul></div> +<div class="para"><p>This describes the arguments, redirections, and environment of a +command to run in a sub-process.</p></div> +<div class="para"><p>The caller:</p></div> +<div class="olist"><ol> <li> <p> allocates and clears (memset(&chld, 0, sizeof(chld));) a @@ -383,14 +431,14 @@ calls finish_command(). </p> </li> -</ol> -<p>The .argv member is set up as an array of string pointers (NULL +</ol></div> +<div class="para"><p>The .argv member is set up as an array of string pointers (NULL terminated), of which .argv[0] is the program name to run (usually without a path). If the command to run is a git command, set argv[0] to -the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p> -<p>The members .in, .out, .err are used to redirect stdin, stdout, -stderr as follows:</p> -<ol> +the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p></div> +<div class="para"><p>The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows:</p></div> +<div class="olist"><ol> <li> <p> Specify 0 to request no special redirection. No new file descriptor @@ -454,10 +502,10 @@ redirected.</tt></pre> </div></div> </li> -</ol> -<p>To modify the environment of the sub-process, specify an array of -string pointers (NULL terminated) in .env:</p> -<ol> +</ol></div> +<div class="para"><p>To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env:</p></div> +<div class="olist"><ol> <li> <p> If the string is of the form "VAR=value", i.e. it contains <em>=</em> @@ -470,20 +518,20 @@ variable that will be removed from the child process's environment. </p> </li> -</ol> -<p>To specify a new initial working directory for the sub-process, -specify it in the .dir member.</p> -<ul> +</ol></div> +<div class="para"><p>To specify a new initial working directory for the sub-process, +specify it in the .dir member.</p></div> +<div class="ilist"><ul> <li> <p> <tt>struct async</tt> </p> </li> -</ul> -<p>This describes a function to run asynchronously, whose purpose is -to produce output that the caller reads.</p> -<p>The caller:</p> -<ol> +</ul></div> +<div class="para"><p>This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads.</p></div> +<div class="para"><p>The caller:</p></div> +<div class="olist"><ol> <li> <p> allocates and clears (memset(&asy, 0, sizeof(asy));) a @@ -515,13 +563,13 @@ calls finish_async(). </p> </li> -</ol> -<p>The function pointer in .proc has the following signature:</p> +</ol></div> +<div class="para"><p>The function pointer in .proc has the following signature:</p></div> <div class="literalblock"> <div class="content"> <pre><tt>int proc(int fd, void *data);</tt></pre> </div></div> -<ol> +<div class="olist"><ol> <li> <p> fd specifies a writable file descriptor to which the function must @@ -542,11 +590,11 @@ report failure as well. </p> </li> -</ol> -<p>There are serious restrictions on what the asynchronous function can do +</ol></div> +<div class="para"><p>There are serious restrictions on what the asynchronous function can do because this facility is implemented by a pipe to a forked process on -UNIX, but by a thread in the same address space on Windows:</p> -<ol> +UNIX, but by a thread in the same address space on Windows:</p></div> +<div class="olist"><ol> <li> <p> It cannot change the program's state (global variables, environment, @@ -560,11 +608,11 @@ facility also uses. </p> </li> -</ol> +</ol></div> </div> <div id="footer"> <div id="footer-text"> -Last updated 02-Jul-2008 03:02:22 UTC +Last updated 2008-07-20 01:23:36 UTC </div> </div> </body> diff --git a/technical/api-run-command.txt b/technical/api-run-command.txt index 3e1342a..75aa5d4 100644 --- a/technical/api-run-command.txt +++ b/technical/api-run-command.txt
@@ -30,7 +30,7 @@ start_command() followed by finish_command(). Takes a pointer to a `struct child_process` that specifies the details. -`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: +`run_command_v_opt`, `run_command_v_opt_cd`, `run_command_v_opt_cd_env`:: Convenience functions that encapsulate a sequence of start_command() followed by finish_command(). The argument argv
